511 Data Exchange 
including an 
Open511 Protocol 


June 19, 2020 


Version I.I 


(m) 


METROPOLITAN 
TRANSPORTATION 


COMMISSION 


(> 511 Data Exchange Specification 


METROPOLITAN 
TRANSPORTATION 


COMMISSION 


EF 
i 


| UDIE 





1.0 511 Data Exchange including an Open5 | I Protocol...........ernsenranvrsvsvrnvrnvensenessessessensensenessessessensensansesessessensensenen 2 
1.1 Why 51 I Data Exchange?........eoseessosessesvesvensensavesvessensensessesessessensensessevessessensensevsssessessensensesssversessensensassssessessensenser 2 
(2 Contributions estes nhun innn hunn henen niknuti nn innn an 2 
1.3 What is 51 I Data Exchange.......s.ssoseosvovenvonsonsovvrvvsvensensensesesvessensensessavessersensensavsasessessensensessssessessensensessssessessensenser 2 
1.4 Locating 511 Data Resources.........srsessrnsrnsassasessessensensensavessessensensessasessessensensansssessessensensessssessessensensassssessessensenser 3 

2.0 51 I Data Exchange Communication Protocol.........e.ssrsrasvnvvnsensenanvavvsvensensensasesversessensensesesvessessensensessssessessensensene 4 
2.1 Data Exchange Standards, Delivery Mechanism, and Encoding........emnsonsonvovvnvvnvrnsensavvrvvsvensensensasessessensensesen 4 
225 6 
2.3 51 I Data Types/Resources ......emsernsesessessrnsensenrasessessensenseseasessessensensessasessersensensassssessessensensasessessessensessasessessensensenen 6 
2.4 API: Discovery .....seesrssesenvesersersessensensasessessessensessasessessessensessssessessensensessasessessensensavsssessensensensavessessessensensasessessensensenen 7 
2:5: APL Jurisdietionunensuemegdenrrlnheeekengdønjenbjeniønijuiiasiir 10 
2.6 API: Jurisdiction Geography. ........sessscsecsecsessssessecsecsscusseeseesecsscuscussessecsecuscussussecsecsecussussusseesecseeuseusseeaeeseeneenseness 12 

TEEN 14 
3.1 Data Encoding .......sonsonsonvosvrsvnsrnsensenersersessensensavsasessessensensessssessessensensevsssessessensensevsssessensensensassssessensensensasessessensensenen 14 
3.2 Authentication and Encryption Mechanisms........e.ssasvnvvnvrnvensensevvrvvrsensensensesessessensensensavessersessensessevessessensensenen 14 
3.3 Response Language ......ssosvnvvnvvnvensenrvvnvvnvensenseneeversensensensesessessessensensavessessessensensasessessensensensasessessensensessesessessensensenen 14 
3.4 API Rate and Throttling.......sonsonsonvonvnvvnvonsensenvrvvrvensensensesesvessensensensesessessensensensesessessensensensasessessensensessavessessensensenen 15 
3.5 Cross domain requests ........ennsrnsanvvvvnvvnsensensansaversensensensevsasessessensensavessessensensensasessessensensensasessessensensessesessessensensenen 15 
3:6 Next steps Vanene n n n pR Ann A nh na a R 15 

Appendix A: API Response Messages- XML ....rnnrnsrnvrnsenvasvrsvsvenvensensaseavessessensensessasessessensensessavessessensensensasessessensensenser 16 
FT Ge Lur 16 

Appendix B: API Response Messages- JSON .....nsnsrnsensenvavvrsvssensensensaseavesvessensensessasessessensensessavessessensensensasessessensensenser 20 
Section |: General JSON.........essessrnsrnsenveseevenvrnsrnseseesessensensensaseesesvensenseneeseesessensensensesessensensensaneesessensensenseseesensensensenser 20 


September 24,2014 Page 2 of 28 


(m 511 Data Exchange Specification 


METROPOLITAN 
TRANSPORTATION 


COMMISSION 


A.1.1 Example Discovery Response (XML)........srnsrnvrnsenvanvrvvsvrnvensensanesvessessensensaseasessessensensessasessessensensensasessessensensenser 16 
A.1.2 Example Jurisdiction Response (XML)... ssessssssessecsscsssssseeseesecsecsscussscsecseesecuscussussecasenecuceussusseeseaseuseneenese 19 
A.1.3 Example JurisdictionGeography Response (XML) ............sssssssecsecsecsscssesseeseescessenssuesecseucenseussussneaesseneensenses 20 
B.1.1 Example Discovery Response (JSON).........nnrsnnsrnranvrsvrvvnvenvensensasvsvessensensensavessessensensensavessessessensensassssessessensensene 20 
B.1.2 Example Jurisdiction Response (JSON)..........snnsrnsonvrvvnvvnvrnsrnsansavessessensensensasessessessensensasessersessensensavsssessersensensene 23 
B.1.3 Example Jurisdiction GeographyResponse (JSON) uu... esssessecsecsscsssssseesecsecuccuscussessecsecuecuscussecaeneencensensaes 25 


September 24,2014 Page 3 of 28 


(m 511 Data Exchange Specification 


METROPOLITAN 
TRANSPORTATION 


COMMISSION 


Document History 


Description Version Date č | 


Working Draft - addressed reorganization comments 09 08/28/13 
First published version with transit, traffic, tolling, and 09/13/13 
parking APIs 


Update Traffic APls' structure information, parameters 

and filters, and their examples to sync with 5/2/2014 
specification provided on Open5I l.org. 

Add GTFS-realtime Trip Updates and Vehicle 5/7/2014 
Positions, and their examples. 


Minor updates and corrections | Minor updates and corrections 110] 5/28/2014 


Add sample request endpoint and parameters and 
filters tables for Section 3.14 and 3.15. Update 

6/12/2014 
references for resource endpoints with their exact 
URL. 
Minor updates to Section 3.14 and 3.15 mo 7117/2014 
Split the API specification document to have a separate 09/24/2014 
Genearl document covering common sections 
Updated API Responses | Updated API Responses = sda 02/05/2020 





September 24, 2014 Page I of 28 


(> 511 Data Exchange Specification 


METROPOLITAN 
TRANSPORTATION 


COMMISSION 





1.1 Why 511 Data Exchange? 


511 systems across North America collect and disseminate traveller information to public for free. 
Government entities — state and/or regional, provide traffic, transit, bicycling, and ridesharing 
information, depending on the agency’s mandate and jurisdiction, for their respective population through 
abbreviated phone number, 511, as well as web and other dissemination channels such as mobile web, 
smartphone apps, SMS, and large-screen display devices and kiosks. 51 I systems host a wealth of 
traveller information that can be a valuable resource for innovative application development by external 
parties if the data can be exposed through a data exchange standard. In addition to sharing data with 
developers, adoption of standard based data exchange would also help share data between a 51 I system 
and other data sources, a transit agency for example, as well as neighbouring 51 I systems, facilitating 
traveller information across neighbouring 51 I jurisdictions. 


Each 51 I system has developed its own mechanism to collect data and disseminate information. An open 
standard for disseminating data would help 51 I data consumers easily access data and develop their 
products based on a set of known interfaces. Open5 I lis a newly designed open standard that defines a 
set of data interfaces in order to facilitate access to 51| data. These interfaces are intended to benefit 
both internal and external traveller application development. 


1.2 Contributions 

MTC and OpenNorth developed the initial draft. A group of stakeholders from government and private 
sectors have contributed by providing valuable feedback through the Open5l I community 
(http://open5 | l.org). 


1.3 What is 511 Data Exchange 


Each 51 I system collects data and disseminates information relevant for travellers within a given 
geographical jurisdiction. The 51 I data exchange adopts a set of existing standards for data collection 
and dissemination. In addition, it also includes a new and open data dissemination interface standard, 
named Open51 I, and targeted for data consumers delivering end-user applications. The following 
principles guided the development of 51 I data exchange and the Open5| I: 


e At one end 51 I systems collect data from various public (DOTs, cities/counties, transit agencies, 
etc.) and private (traffic data vendors) sector data generators. At the other end data is 
consumed by internal and external applications. 51 I data exchange specifications should facilitate 
both data collection and dissemination. 


e A number of traffic and transit data exchange standards exist that are well known in the 
industry. SIRI, NeTEx, GTFS, and GTFS-Realtime for transit data and TMDD for traffic data to 
name a few. 511 data exchange specifications should adopt a suitable existing standard where it 
serves the data exchange use case. 


e Because some of the existing standards do not lend themselves to wider use due to inherent 
technical complexity and additional data processing, a simple and open data interface should be 
supported to facilitate direct consumption. 


e 511 data exchange specification should describe: 
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= Communication protocol that establishes the relationship between two interacting 
systems including security, authentication, data access privileges, and system status 
awareness. 

= Protocol for locating 511 data resources; metadata services for geographical coverage 
(cities, counties), travel modes (traffic, transit, bicycling, ridesharing, walking, parking, 
air), and transportation infrastructure/service types (highway/arterial/local for traffic, 
bus/ferry/train for transit). 

= Data seeking and delivery mechanisms. 


= Data structure and encoding formats. 


1.4 Locating 511 Data Resources 

511 data disseminators may decide the best way to disseminate data. An online registry for 51 I data 
resources similar to GTFS Data Exchange (http://www.gtfs-data-exchange.com) would make 51 I data 
more widely available. The online registry may provide a service that can be queried to get a list of 51 I 
data resources and saved locally in order to support resource discovery. 51 I data disseminators should 
also provide online information about their own open 511 data resources. 


September 24, 2014 Page 3 of 28 


(m 511 Data Exchange Specification 


METROPOLITAN 
TRANSPORTATION 


COMMISSION 


ata Exehanane Commiinics on rotor 


Communication for 511 data exchange incorporates a simple, easy to implement protocol. 


e Each data disseminator would decide whether or not a license agreement and/or Terms of Use 
are required by an external consumer to access data. To make data easily accessible such 
requirements should be as simple and streamlined as possible to encourage wider use of the 
data. 

e If a registration is required to access data, that process may be used to identify data needs by 
the registrant. Successful registration should result in an authentication key/ID provided to the 
consumer. 

e Data requests should be accompanied with a valid key/ID and would be limited to the granted 
privileges. 

e Communication protocol for 511 data collection would be set up as per the mutual agreement 
between the two organizations. 


2.1 Data Exchange Standards, Delivery Mechanism, and Encoding 

511 data exchange involves both bulk and ad-hoc query-based data sharing. Bulk data exchange would 
provide large volume of data, useful for C2C (center to center) communication whereas app developers 
are mostly interested in ad-hoc, on demand data in small quantities. Data users who prefer to store data 
in their own system would choose bulk data transfer. On the other hand, a mobile application would 
need small data packaged in readily consumable format that the query based APls would fulfil. 


511 data exchange specifications take advantage of existing standards, when feasible. Existing standards 
that are adopted as 51 I standards are travel mode specific. Table | and 2 below provide adopted 51 | 
data exchange standards, delivery mechanism, and encoding for transit and traffic data. Travel modes 
other than traffic and transit will be added to this standard later. 


In discussions with agencies and developer community it became obvious that one particular data and 
communication standard cannot fulfil everyone’s needs. For example, agencies producing traffic data 
prefer standards such as TMDD for data sharing with other agencies. On the other hand, a developer 
working on a mobile application for traffic information is more comfortable using widespread REST 
based APIs and JSON/XML data format. Though standards like TMDD are very comprehensive and 
accepted in the ITS industry they are often seen as heavy and cumbersome by the developer community 
who are primarily interested in building a simple web/mobile based application. Therefore, it was 
necessary to address this diversity in use cases by adopting TMDD for low level (bulk) data 
communication between agencies and local data storage and a REST based Open5 | I API providing data 
in both XML and JSON formats.5 | I data to be collected and disseminated can be broadly classified into 
two categories: 


Configuration data — This category includes data that are mostly static and defines the configuration 
of a transportation system. For example, routes and stops for a transit service or the roadway network 
for traffic do not change frequently. Configuration data is very important because of the fact that real- 
time information is based on the underlying configuration data. Most users would like to download, save, 
and perform additional processing on configuration data before it is consumed in smaller pieces by their 
system and applications. Because configuration dataset for a transportation system/service would be 
large in size, it is efficient to provide this bulk data through transport mechanism such as FTP or data 
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downloadable over HTTP. When it is necessary to provide configuration data in small quantities it will 
be done through Open511 APIs over Request/Response based communication. 


Real-time data—Data in this category generally has a short life time and changes frequently. Data such 
as transit departure predictions, and incidents and travel times on roadway fall in this category. Whether 
used in bulk or through Open5 11 APIs real-time data should be provided through a Request/Response 
based communication. 


Based on the amount of data exchanged and data encoding used, 511 data exchanges have been 
organized into two groups, bulk and query-based. Bulk data exchanges provide data using data encoding 
adopted by the given standard. Encoding for query-basedOpen5l I APIs can be JSON, XML, or both. 
Depending on the use case some users may choose bulk exchanges using standards such as TMDD for 
both configuration and real-time, some may use only Open5l I APls for configuration and real-time data, 
others may first download configuration data to provide the foundation for their application and make 
ad-hoc queries through the Open5 | I API calls for real-time data. Table | and 2 below provide a 
summary of bulk and query-based data exchanges, respectively. 


Table 1 511 Adopted Standards, Delivery Mechanisms and Encodings for Bulk 
Exchanges 


Data Type 


Data 
Definition! 


Pattern of 
Interaction” 


Data 
Transport 


Data 
Encoding 


Status 





Transit 


Service 
configuration and 
scheduled 
timetable 


GTFS, 
NeTEx? 


Downloaded 


HTTP 


GTFS: 
CSV 
NeTEx: 
XML 


Available 





Predicted and 
unplanned changes 
data 


SIRI, GTFS- 
RT 


Request/Response 


SIRI: XML 
GTFS-RT: 
Proto 
Buffer 


Undeveloped 





Network 
configuration 
data 


TMDD V3.0 


Request/Response 


XML 


Undeveloped 








incidents data 





TMDD V3.0 





Request/Response 








XML 





Available 





Table 2 Open 511 Data Standards, Delivery Mechanism and Encoding for Query-Based 
Exchanges 


Travel 
Mode 


Data Type 


Data 
Definition! 


Pattern of 
Interaction 


Data 
Transport 


Data 
Encoding 


Status 





Transit 





Service configuration 
and scheduled 
timetable 
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Request/Response 





HTTP 





JSON/XML 





Available 
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Predicted and 


unplanned dinges Request/Response JSON/XML | Undeveloped 





Road network 


I . Open51 I Request/Response JSON/XML | Undeveloped 
configuration 





Traffic | Real-time speed Request/Response Undeveloped 





Incidents Open51 I Request/Response JSON/XML | Available 





Configuration, and 
Tolling | static and dynamic Custom‘ Request/Response JSON/XML | Undeveloped 























1. GTFS — General Transit Feed Specification, GTFS-RT — GTFS for real-time transit information, SIRI — Service 
Interface for Real-Time Information, TMDD — Traffic Management Data Dictionary. 

2. All bulk data exchange interactions will be preceded by new data availability notification to registered 
data subscribers. 

3. Each 511 system may adopt a suitable custom data exchange standard that facilitates transit data 
collection from transit agencies within its jurisdiction. For example, San Francisco Bay Area 511 has 
developed an XML schema that is currently being used by Bay Area transit agencies to provide data to the 
511 system. The custom XML schema may get replaced in future by an enhanced GTFS. 

4. May get adopted in the Open511 in future. 


2.2 Opend11 


Open5 I I aims to create simple, uniform and resource driven APls that can be easily used by consumers 
to retrieve data from 511 systems. In order for these APIs to be easily discovered Open5 | I API 
providers must create a single entry discovery point that provides links and details for all other 
resources available from a disseminator/Jurisdiction. Open5 1 I defines a discovery resource that will help 
consumers locate APIs and other resources. Also, to provide a context of the data and other details, 
Open5l I recommends defining a Jurisdiction resource which will provide details on the jurisdiction and 
its coverage. 


2.3 511 Data Types/Resources 

As shown in the tables above, 511 data exchange adopts existing data standards such as GTFS and 
TMDD, where those standards are most suitable. Information on adopted standards can be obtained 
from online resources as listed below. 


Transit (service configuration and schedules) 
GTFS: https://developers.google.com/transit/gtfs/ 


NeTEx: http://www.kizoom.com/standards/netex/ 
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Transit (real-time information 
GTFS-RT: https://developers.google.com/transit/gtfs-realtime/ 





SIRI: http://www.kizoom.com/standards/siri/ 


Traffic 
TMDD: http://www. ite.org/standards/tmdd/ 





Open5 | |: http://open5 | l.org/ 


Since Open5 | I specification is fairly new and evoloving, please refer to the above website for latest 
updates. 


In addition, data types for Open5I I APls are defined below. 


2.4 API: Discovery 

Open5 I | recommends providing an API discovery mechanism/endpoint similar to open31 I. 
Jurisdictions/disseminators will setup a service directory that will list all available resources that are 
currently supported by a jurisdiction and their endpoints. The service directory will also provide 
information on endpoints for multiple versions. 


The structure of an API discovery document consists of 


Per / 


List all the See that are 

supported by the endpoint. Most of 

the time, there will be only one 
Collection of occurrence, except for multiple 
jurisdiction Mandatory jurisdictions endpoints and 

aggregators. 

At least one jurisdiction element is 

ee (| i 


Free text Mandatory Full text name of the jurisdiction. 


Link to the jurisdiction resource. In 
XML, the rel attribute needs the 
value self. An aggregator should 

— self/url Hink Mandatory always point the original 
jurisdiction resource and not copy 
it locally. 


: Collection of Mandat List all the services supported by 
services service anaalory — | the endpoint. 


Most service types are explained 
in the 511 SF Bay Data 

— service_type Link Mandatory Specification documents. Relevant 
data specification can be 
downloaded using the URL 
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provided in this field. Any other 
service types will be defined by an 
external URL. 


Link pointing to the resource. In 
XML, the rel attribute needs the 
value self. Even if the current 
endpoint supports multiple 

— self/url ED Mandatory jurisdictions or is an aggregator, 
there is only one service resource 
that aggregates the data for all the 
jurisdictions. 


ted . Collection of Optional List all the versions supported by 
= SUppOrned versions supported version | ”P"0na the current server. 


Version identifier. As the 
specification evolves, version 
— supported version | Enum Optional identifiers will be added. For the 
= moment, the only version 
supported is v0 and is not an 
official value. 


Sample request endpoint for discovery 


Request Endpoint http://api.511.org 
Example 


Parameters and Filters 











The discovery resource does not support any URL parameter or filter besides the format and the 
version negotiation. The discovery response for XML is shown in Appendix A Section A.1.1. The 
discovery response for JSON is shown in Appendix B Section B.1.1. 


Mandatory/ ES 


The response format (json/xml) desired. If none specified, then 
default response would be JSON. 
e.g. 

Optional ?format=json 
(returns json respone for vi, if vi is the latest version or 
specified version via parameter) 
?format=xml 





The version of Open511 desired. 
e.g 
Optional 
?version=v1 
(returns response for v1 in conjunction with format requested. 
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api key Unique key assigned to a user after they signup for Open511. 


Possible Errors 





The numbers represent the HTTP status code returned for each error type: 


e 401 — Unauthorized (Invalid API key) 


e 500 - Internal Server Error (System has issues processing your request) 


September 24, 2014 Page 9 of 28 


(m) 511 Data Exchange Specification 


METROPOLITAN 
TRANSPORTATION 


COMMISSION 


2.5 API: Jurisdiction 


The jurisdiction represents any government entity (city, state/province, agency, etc.) that publishes 
Open51 I data. It is a functional concept used to provide metadata such as contact information, etc. 


The structure of a Jurisdiction resource consists of 


Mandatory ds 
Mandatory | Self link to the current resource. 


Unique identifier for the jurisdiction. It's expected to 
be unique across all Open511 implementations. It 
must take the form of a hostname within a domain 
owned by the government entity. The hostname 

Mandatory | doesn't necessarily need to resolve in DNS; for 
example, if Roadsville owns roadsville.gov, it's fine 
to create agency1.roadsville.gov and 
agency2.roadsville.gov jurisdictions, even if those 
don't resolve to IP addresses. 


[names Freetext | Mandatory | Name of the jurisdiction, OO) 
Valid email that can be used to contact the 
Mandatory | department or the person in charge of the data 
provided by the Open511 API. 
Link pointing to a human readable resource (web 
description page, pdf file, etc) providing details about the 
Open511 service and the jurisdiction covered. 


Phone number to contact the department or person 
in charge of the data provided by the Open51 1 
API. 


Free text that can be used by a client application to 
description provide some information about the Open51 1 
service and the jurisdiction covered. 





The geography field links an open511 jurisdiction 
geography geography resource providing the jurisdiction 
boundaries. 

The timezone of the jurisdiction; will be used as the 
default for events belonging to this jurisdiction. 
Should always be provided, except in cases where 
a jurisdiction spans multiple timezones. 

The unit this jurisdiction uses to measure 
distances. Can be KILOMETRES or MILES, but 
kilometres are the default and so jurisdictions using 
kilometres need not specify a distance_unit. 


Link to a resource containing the license covering 
languages Saera amar List of languages supported by this endpoint. A 
languages Optional language element should be provided for each 
language supported. 
Multiple occurrences supported. The values 
— language Enum Mandatory | supported are the same as the language 
negotiation feature. 


Sample request endpoint for jurisdiction 


timezone Optional 


distance_unit Enum Optional 
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Request Type 





Request Endpoint For e.g. http://api.511.org/jurisdictions 
Example 








Parameters and Filters 





The jurisdiction resource does not support any URL parameter or filter besides the format selection 
and the language negotiation. The jurisdiction response for XML is shown in Appendix A Section A.1.2. 
The discovery response for JSON is shown in Appendix B Section B.1.2. 


Mandatory/ pore 


The response format (json/xml) desired. If none specified, then 
default response would be JSON. 
e.g. 

Optional ?format=json 
(returns json respone for v1, if v1 is the latest version or 
specified via version parameter) 
?format=xml 


The version of Open511 desired. 
e.g 
Optional 
?version=v1 
(returns response for v1 in conjunction with format requested. 


Unique key assigned to a user after they signup for Open511. 


Possible Errors 





The numbers represent the HTTP status code returned for each error type: 


e 401 — Unauthorized (Invalid API key) 


e 500 - Internal Server Error (System has issues processing your request) 
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2.6 API: Jurisdiction Geography 


The jurisdiction geography represents the boundaries of the jurisdiction. 


The structure of a Jurisdiction resource consists of 


Mandatory RT 





decaraniy GeoSpatial Mandatory Seen the jurisdiction; a Polygon or 


Sample request endpoint for jurisdiction 








Request Type 





Request Endpoint For e.g. http://api.51 1.org/jurisdictions/geography 
Example 
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Parameters and Filters 





The jurisdiction geography resource does not support any URL parameter or filter besides the format 
selection. The jurisdiction response for XML is shown in Appendix A Section A.1.2. The discovery 
response for JSON is shown in Appendix B Section B.1.2. 


Mandatory/ er, 


The response format (json/xml) desired. If none specified, then 
default response would be JSON. 
e.g. 
Optional ?format=json 
(returns json respone for v1, if v1 is the latest version or 
specified via version parameter) 
?format=xml 
(returns XML response for v1) 


The version of Open511 desired. 
e.g 
Optional 
?version=v1 
(returns response for v1 in conjunction with format requested. 


Unique key assigned to a user after they signup for Open511. 


Possible Errors 





The numbers represent the HTTP status code returned for each error type: 


e 401 — Unauthorized (Invalid API key) 


e 500 - Internal Server Error (System has issues processing your request) 
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3.0 Technical Guidelines 


3.1 Data Encoding 
Character encoding is in UTF-8 for all the APIs developed using SIRI, Natex and Open5 | I. 


APIs developed under Open5 I I follow additional guidelines proposed by Open5 1 I specifications. Please 
refer to http://open5 | l.org/guidelines.html for details. 





3.1.1 Response Serialization: XML and JSON 
Both JSON and XML serialization are supported, with JSON being default serialization format. 


XML data is serialized following XSD provided by the specification. 
Please refer to https://www.vdv.de/siri.aspx for details regarding data serialization for SIRI based APIs. 


Please refer to http://open5 | |.org/guidelines.html for details regarding data serialization for Open5 | I 
based APIs. 





3.1.2 Format and version negotiation 
Format and version negotiation is done via HTTP headers and/or a queystring parameter (See 
http://open5 I |.org/guidelines.html ) 





Users can indicate their format preference via one of two mechanisms: 
e By using the Accept HTTP header and specifying application/json and application/xml as types. 


e — By specifying ?format=json and ?format=xml in URL parameter. If provided, it takes precedence 
over the Accept header. 


Users may request responses conforming to a specific Open5 1 | version via one of two mechanisms 
(Only applies to Open5 | | based APIs): 


e By specifying an Open5 1 I -Version header, with the desired version string as a value, e.g. 
Open5 1 I-Version: vl 


e By specifying ?version=v| in URL parametre. If provided, it takes precedence over the 
Open3I I-Version header. 


3.2 Authentication and Encryption Mechanisms 


For accessing these APIs, users must use API keys (tokens). That token must be sent via an api key 
querystring parameter. Users can signup for new token at http://{token_URL} 


3.3 Response Language 
Even though Open511 is capable to support multiple languages; the current implementation for 
Open5 | I based APIs is unilingual. Each API response includes a lang attribute set to "en". 
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3.4 API Rate and Throttling 


In order to avoid excessive load and usage on system, access to APls has been restricted based on 
usage. Each API will have throttle limt defined and when throttle limits are exceeded by a consumer, 
appropriate messages and response code will be provided for subsequent requests. For e.g. if the Traffic 
Segment API has a request limit of 60 requests/hour per api_key and if a consumer requests the API 
more than 60 times in a hour, the API response would comeback with 429 - Too Many Requests. 


3.5 Cross domain requests 
All the above listed APIs support cross-domain requests, via both: 


— JSONP, using a parameter named callback. Example: ...?callback=func name 
— CORS, by including an Access-Control-Allow-Origin: * header in all responses to GET queries 


3.6 Next steps? 

Open5 I I specifications may add additional travel modes such as parking, tolling, ridesharing, bicycling, 
etc. and additional data services for modes already in the specifications. Modification and enhancement 
to this specification will follow a systematic versioning scheme. 
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Section 1 — General XML 


A.l.l Example Discovery Response (XML) 

<open511 xml:lang="en" xml:base="http://api.511.org" version="v1"> 
<jurisdictions> 

<jurisdiction> 

<id>511.org</id> 

<name>511 SF Bay</name> 

<link rel="self" href="http://api.511.org/jurisdictions/"/> 
</jurisdiction> 

</jurisdictions> 

<services> 

<service> 

<link rel="self" href="/transit/datafeeds"/> 

<link rel="service type" href="https://developers.google.com/transit/gtfs"/> 
<supported_versions> 

<supported version>vi</supported version> 

</supported_versions> 

</service> 

<service> 

<link rel="self" href="/traffic/events"/> 

<link rel="service type" 
href="https://511.org/sites/default/files/pdfs/511%2ØSF%2ØBay%2Ø0pen%2ØData%2ØSpecifica 
tion%20-%20Traffic.pdf"/> 

<supported_versions> 

<supported_version>v2</supported_version> 

<supported version>vi</supported version> 

</supported_versions> 

</service> 

<service> 

<link rel="self" href="/transit/gtfsoperators"/> 

<link rel="service type" 
href="https://511.org/sites/default/files/pdfs/open%2Ødata/511%2ØSF%2ØBay%2Ø0pen%20Data 
%2ØSpecification%2Ø-%2ØTransit.pdf"/> 

<supported versions> 

<supported version>vi</supported version> 

</supported_versions> 

</service> 

<service> 

<link rel="self" href="/transit/holidays"/> 

<link rel="service type" 
href="https://511.org/sites/default/files/pdfs/open%2Ødata/511%2ØSF%2ØBay%2Ø0pen%2ØData 
%2ØSpecification%2Ø-%2ØTransit.pdf"/> 

<supported versionss 

<supported version>vi</supported versions 

</supported_versions> 

</service> 

<service> 

<link rel="self" href="/transit/lines"/> 

<link rel="service type" 
href="https://511.org/sites/default/files/pdfs/open%2Ødata/511%2ØSF%2ØBay%2Ø0pen%2ØData 
%2ØSpecification%2Ø-%2ØTransit.pdf"/> 

<supported versions> 

<supported version>vi</supported versions 

</Supported versions> 
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</service> 

<service> 

<link rel="self" href="/transit/operators"/> 

<link rel="service type" 
href="https://511.org/sites/default/files/pdfs/open%2Ødata/511%2ØSF%2ØBay%2Ø0pen%2ØData 
%2ØSpecification%2Ø-%2ØTransit.pdf"/> 

<supported versions> 

<supported version>vi</supported versions 

</supported_versions> 

</service> 

<service> 

<link rel="self" href="/transit/patterns"/> 

<link rel="service type" 
href="https://511.org/sites/default/files/pdfs/open%2Ødata/511%2ØSF%2ØBay%2Ø0pen%20Data 
%2ØSpecification%2Ø-%2ØTransit.pdf"/> 

<supported versions> 

<supported version>vi</supported versions 

</supported_versions> 

</service> 

<service> 

<link rel="self" href="/toll/programs"/> 

<link rel="service type" href="http://open511.org/services/tolls"/> 
<supported_versions> 

<supported version>vi</supported version> 

</supported_versions> 

</service> 

<service> 

<link rel="self" href="/transit/servicealerts"/> 

<link rel="service type" href="https://developers.google.com/transit/gtfs - 
realtime/service-alerts"/> 

<supported_versions> 

<supported version>vi</supported version> 

</supported_versions> 

</service> 

<service> 

<link rel="self" href="/transit/shapes"/> 

<link rel="service type" 
href="https://511.org/sites/default/files/pdfs/open%2Ødata/511%2ØSF%2ØBay%2Ø0pen%2ØData 
%2ØSpecification%2Ø-%2ØTransit.pdf"/> 

<supported versions> 

<supported version>vi</supported versions 

</supported_versions> 

</service> 

<service> 

<link rel="self" href="/transit/stopmonitoring"/> 

<link rel="service type" 
href="https://511.org/sites/default/files/pdfs/open%2Ødata/511%2ØSF%2ØBay%2Ø0pen%20Data 
%2ØSpecification%2Ø-%2ØTransit.pdf"/> 

<supported versions> 

<supported version>vi</supported version> 

</supported_versions> 

</service> 

<service> 

<link rel="self" href="/transit/stopplaces"/> 

<link rel="service type" 
href="https://511.org/sites/default/files/pdfs/open%2Ødata/511%2ØSF%2ØBay%2Ø0pen%2ØData 
%2ØSpecification%28Ø-%2ØTransit.pdf"/> 

<supported versions> 

<supported version>vi</supported versions 
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</supported_versions> 

</service> 

<service> 

<link rel="self" href="/transit/stops"/> 

<link rel="service type" 
href="https://511.org/sites/default/files/pdfs/open%2Ødata/511%2ØSF%2ØBay%2Ø0pen%20Data 
%2ØSpecification%2Ø-%2ØTransit.pdf"/> 

<supported versions> 

<supported version>vi</supported versions 

</supported_versions> 

</service> 

<service> 

<link rel="self" href="/transit/stoptimetable"/> 

<link rel="service type" 
href="https://511.org/sites/default/files/pdfs/open%2Ødata/511%2ØSF%2ØBay%2Ø0pen%20Data 
%2ØSpecification%2Ø-%2ØTransit.pdf"/> 

<supported versionss 

<supported version>vi</supported versions 

</supported_versions> 

</service> 

<service> 

<link rel="self" href="/transit/timetable"/> 

<link rel="service type" 
href="https://511.org/sites/default/files/pdfs/open%2Ødata/511%2ØSF%2ØBay%2Ø0pen%2ØData 
%2ØSpecification%2Ø-%2ØTransit.pdf"/> 

<supported versions> 

<supported version>vi</supported versions 

</supported_versions> 

</service> 

<service> 

<link rel="self" href="/traffic/traffic segments"/> 

<link rel="service type" href="http://open511.org/services/traffic_segments"/> 
<supported versions> 

<supported version>vi</supported version> 

</supported_versions> 

</service> 

<service> 

<link rel="self" href="/transit/tripupdates"/> 

<link rel="service type" href="https://developers.google.com/transit/gtfs - 
realtime/trip-updates"/> 

<supported_versions> 

<supported version>vi</supported version> 

</supported_versions> 

</service> 

<service> 

<link rel="self" href="/transit/vehiclemonitoring"/> 

<link rel="service type" 
href="https://511.org/sites/default/files/pdfs/open%2Ødata/511%2ØSF%2ØBay%2Ø0pen%2ØData 
%2ØSpecification%2Ø-%2ØTransit.pdf"/> 

<supported versions> 

<supported version>vi</supported versions 

</supported_versions> 

</service> 

<service> 

<link rel="self" href="/transit/vehiclepositions"/> 

<link rel="service type" href="https://developers.google.com/transit/gtfs - 
realtime/vehicle-positions"/> 

<supported_versions> 

<supported version>vi</supported version> 
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</supported_versions> 

</service> 

</services> 

<link rel="self" href="/?api_key=ed7a295f-72fc-47b0-90c1- 
7266a2618bec&operator_id=ba&trip_id=5030852wkdy"/> 
</open511> 











A.l.2 Example Jurisdiction Response (XML) 

<open511 xml:lang="en" xml:base="http://api.511.org" version="v1"> 

<jurisdiction> 

<link rel="self" href="http://api.511.org/jurisdictions/"/> 

<id>511.org</id> 

<name>511 SF Bay</name> 

<email>contact511@511.org</email> 

<phone/> 

<description> 

511's Open Data mission is to provide high quality data to private sector disseminators 
to maximize the number of travelers benefiting from 511 data. 511's Open Data program 
provides several APIs for developers who'd like to create applications, widgets and 
other tools using 511 data. All data sources are provided free-of-charge via token 
request, however, acknowledgement of 511.org as the data provider is required. 
</description> 

<link rel="description" href=" https://511.org/open-data"/> 

<timezone>America/Los Angeles</timezone> 

<distance_unit>MILES</distance_unit> 

<link rel="geography" href="http://api.511.org/jurisdictions/geography"/> 

<link rel="license" 
href="https://511.org/sites/default/files/pdfs/511 Data Agreement Final.pdf"/> 
<languages> 

<language>en</language> 

</languages> 

</jurisdiction> 

<link rel="up" href="/"/> 

<link rel="self" href="/?api_key=ed7a295f-72fc-47b0-90c1- 
7266a2618bec&agency&operator_id=SF"/> 

</open511> 
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A.1.3 Example JurisdictionGeography Response (XML) 
<open511 
xmlns:gml="http://www.opengis.net/gml" 
xml:lang="en" 
xml:base="http://api.511.org" 
version="v1" 





<geographies> 
<geography> 
<gml:Polygon srsName="EPSG:4326"> 
<gml:outerBoundaryIs> 
<gml:LinearRing> 
4gml:coordinates)-73.515580304999958,45. 743558682000106 - 
73.516801182999984, 45. 7/44177048000076 -73.516754262999996,45.745199120000088 - 
73.516741493999973,45.745477517000076 -73.51918957800001,45.746719115000111 - 
73 .519343021999987,45 . 748003618000077 -73.520130775999974,45.748595939009076 - 
73.520120826999971,45.749015964000108 -73.52193461600001,45.750027519000106 - 
73.529479503999994,45 .754234632000113 -73.527583232999973,45.777799543000107 - 
73 .515580304999958, 45 .743558682000106</gml1:coordinates> 
</gml:LinearRing> 
</gml:outerBoundaryIs> 
</gml:Polygon> 
</geography> 

</geographies> 

<link rel="self" href="/jurisdictions/SFBayArea/geography/?apikey={api_key}" /> 

<link rel="up" href="/jurisdictions/SFBayArea/" /> 
</open511> 














Section 1: General JSON 


B.|.1 Example Discovery Response (JSON) 





{ 
"jurisdictions": [ 
{ 
"id": "511.org", 
"name": "511 SF Bay", 
"url": "http://api.511.org/jurisdictions/" 
} 


IE 
"services": [ 
{ 
"service type url": 
"https ://developers.google.com/transit/gtfs", 
"supported versions": [ 
"yq" 

l 


"url": "/transit/datafeeds" 


h 


{ 

"service type url": 
"https://511.org/sites/default/files/pdfs/511%2ØSF%2ØBay%2Ø0pen%2ØData%2ØSpecification% 
20-%20ØTraffic.pdf", 

"supported versions": [ 

"v2", 
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"1" 
ls 
"url": "/traffic/events" 


L 


{ 

"service type url": 
"https://511.org/sites/default/files/pdfs/open%2Ødata/511%2ØSF%2ØBay%2Ø0pen%2ØData%2ØSp 
ecification%2Ø-%2ØTransit.pdf", 

"supported versions": [ 

"yy" 
IE 
"url": "/transit/gtfsoperators" 


h 


{ 

"service type url": 
"https://511.org/sites/default/files/pdfs/open%2Ødata/511%2ØSF%2ØBay%2Ø0pen%2ØData%2ØSp 
ecification%2Ø-%2ØTransit.pdf", 

"supported versions": [ 

"yq" 
l» 
"url": "/transit/holidays" 
} 


{ 
"service_type_url": 
"https ://511.0rg/sites/default/files/pdfs/open%20data/511%20SF%20Bay%200pen%20Data%20Sp 
ecification%20-%20Transit.pdf", 
"supported_versions": [ 
"yq" 
l» 


"url": "/transit/lines" 


} 


{ 

"service type url": 
"https://511.org/sites/default/files/pdfs/open%2@data/511%20SF%20Bay%200pen%2e@Data%2OSp 
ecification%20-%20Transit.pdf", 

"supported versions": [ 

"yq" 

l» 


"url": "/transit/operators" 


h 


{ 

"service type url": 
"https://511.org/sites/default/files/pdfs/open%2Ødata/511%2ØSF%2ØBay%2Ø0pen%2ØData%2ØSp 
ecification%2Ø-%2ØTransit.pdf", 

"supported versions": [ 


"y4" 
ls 
"url": "/transit/patterns" 
L 
{ 
"service type url": "http://open511.org/services/tolls", 
"supported versions": [ 
"yq" 
l» 
"url": "/toll/programs" 
L 
{ 


"service type url": 
"https://developers.google.com/transit/gtfs-realtime/service-alerts", 
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"supported versions": [ 
"yq" 


url": "/transit/servicealerts 


"service type url": 
"https://511.org/sites/default/files/pdfs/open%2Ødata/511%2ØSF%2ØBay%2Ø0pen%2ØData%2ØSp 
ecification%20-%2eTransit.pdf", 

"supported versions": [ 

"yq" 


url": "/transit/shapes" 


"service type url": 
"https://511.org/sites/default/files/pdfs/open%2Ødata/511%2ØSF%2ØBay%2Ø0pen%2ØData%2ØSp 
ecification%2Ø-%2ØTransit.pdf", 

"supported versions": [ 

"y1" 

l» 


"url": "/transit/stopmonitoring" 


js 


{ 

"service type url": 
"https://511.0org/sites/default/files/pdfs/openz2Odata/511420SF420Bay24200pen420Data420Sp 
ecification%20-%2eTransit.pdf", 

"supported versions": [ 

"yq" 


url": "/transit/stopplaces" 


"service type url": 
"https://511.org/sites/default/files/pdfs/open%2Ødata/511%2ØSF%2ØBay%2Ø0pen%2ØData%2ØSp 
ecification%20-%20Transit.pdf", 

"supported versions": [ 

"yi" 
ls 
"url": "/transit/stops" 


js 


{ 

"service type url": 
"https://511.org/sites/default/files/pdfs/open%2Ødata/511%2ØSF%2ØBay%2Ø0pen%2ØData%2ØSp 
ecification%2Ø-%2ØTransit.pdf", 

"supported versions": [ 

"yq" 


l» 
"url": "/transit/stoptimetable" 


L 


{ 

"service type url": 
"https://511.org/sites/default/files/pdfs/open%2Ødata/511%2ØSF%2ØBay%2Ø0pen%2ØData%2ØSp 
ecification%2Ø-%2ØTransit.pdf", 

"supported versions": [ 

"yq" 


ls 


"url": "/transit/timetable" 








L 
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{ 
"service type url": 
"http://open5il.org/services/traffic segments", 
"supported versions": [ 
"yy" 
IE 
"url": "/traffic/traffic segments" 
L 
{ 
"service type url": 
"https ://developers.google.com/transit/gtfs-realtime/trip-updates", 
"supported versions": [ 
"yq" 
l» 
"url": "/transit/tripupdates" 
h 


{ 

"service type url": 
"https://511.org/sites/default/files/pdfs/open%2Ødata/511%2ØSF%2ØBay%2Ø0pen%2ØData%2ØSp 
ecification%2Ø-%2ØTransit.pdf", 

"supported versions": [ 

"a" 

], 

"url": "/transit/vehiclemonitoring" 

hs 
{ 

"service type url": 

"https ://developers.google.com/transit/gtfs-realtime/vehicle-positions", 

"supported versions": [ 


"yy" 
l» 
"url": "/transit/vehiclepositions" 
} 
IE 
"meta": { 
"version": "v1", 
"url": "/?api key=ed7a295f-72fc-47bØ-9Øc1-7266a2618bec&format=json" 
} 











B.1.2 Example Jurisdiction Response (JSON) 
{ 





"id": "511.0rg", 

"url": "http://api.511.org/jurisdictions/", 

"name": "511 SF Bay", 

"email": "contact511@511.org", 

"phone": "" 

"description": "511's Open Data mission is to provide high quality data to 
private sector disseminators to maximize the number of travelers benefiting from 511 
data. 511's Open Data program provides several APIs for developers who'd like to create 
applications, widgets and other tools using 511 data. All data sources are provided 
free-of-charge via token request, however, acknowledgement of 511.org as the data 
provider is required.", 

"description url": " https://511.org/open-data", 

"timezone": "America/Los Angeles", 

"distance unit": "MILES", 

"geography url": "http://api.511.org/jurisdictions/geography", 
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"license url": 
"https://511.org/sites/default/files/pdfs/511 Data Agreement Final.pdf", 
"languages": [ 


en 
J» 
"meta": { 
"version": "v1", 
"url": "/?api key=ed7a295f-72fc-47bØ-9Øc1-7266a2618bec&format=json", 
"up url": "/" 
} 
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B.1.3 Example Jurisdiction GeographyResponse (JSON) 
{ 
"geographies": [ 


"type": "Polygon", 
"coordinates": [ 
[ [71.17,47.33], [-71.15,47.36], [-71.10,47.35], 
[-71.20,47.40], [-71.17,47.33] ] 


] 
} 
], 
"meta": { 
"version": "v1", 
"url": "/jurisdictions/SFBayArea/geography/?apikey={api_key}", 
"up url": "/jurisdictions/SFBayArea/" 
} 
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